package com.googlecode.lightest.core

/**
 * Represents a domain-specific task to be performed in a test. ITask's are
 * typically owned by IDomainSpecificApi's.
 */
interface ITaskResult {
    /**
     * maps numeric status values to their respective String status names, by
     * List index.
     */
    public static final List<String> HUMAN_READABLE_STATUS = [
        'OK',
        'FLAGGED',
        'FAILED',
        'DOOMED'
    ]
    
    // higher numerical values indicate increasing severity
    public static final int STATUS_OK = 0
    public static final int STATUS_FLAGGED = 1
    public static final int STATUS_FAILED = 2
    public static final int STATUS_DOOMED = 3
    
    /**
     * Returns a message describing the result.
     */
    String getMessage()
    
    /**
     * Returns a detailed message about the task execution, for example, the
     * data generated by performing the task, if any.
     */
    String getDetailedMessage()
    
    /**
     * Returns the list of URL's associated with this result.
     */
    List<TaskResultLink> getLinks()
    
    /**
     * Returns the status of the result.
     */
    int getStatus()
    
    /**
     * Returns the task whose performance returned this result.
     */
    ITask getTask()
    
    /**
     * Returns the time the task was started.
     */
    long getStartTime()
    
    /**
     * Returns the time the task was finished.
     */
    long getEndTime()
    
    /**
     * Sets the return value of getMessage().
     *
     * @param message
     */
    void setMessage(String message)
    
    /**
     * Sets the return value of getDetailedMessage().
     *
     * @param detailedMessage
     */
    void setDetailedMessage(String detailedMessage)
    
    /**
     * Adds a URL referencing a resource that provides additional information
     * related to this result, to a collection maintained by the result object.
     * 
     * @param link  the string representation of the URL to add
     */
    void addLink(String link)
    
    /**
     * Adds a URL referencing a resource that provides additional information
     * related to this result, to a collection maintained by the result object.
     * 
     * @param link  the link object to add
     */
    void addLink(TaskResultLink link)
    
    /**
     * Sets the time the task was started.
     */
    void setStartTime(long startTime)
    
    /**
     * Sets the time the task was finished.
     */
    void setEndTime(long endTime)
    
    /**
     * Sets the parent task result.
     * 
     * @param parentResult
     */
    void setParent(ITaskResult parentResult)
    
    /**
     * Returns the parent task result.
     */
    ITaskResult getParent()
    
    /**
     * Adds to the list of child task results.
     */
    void appendChild(ITaskResult childResult)
    
    /**
     * Returns a list of child task results.
     */
    List<ITaskResult> children()
    
    /**
     * Sets the status of this result to STATUS_FLAGGED, but only if it is not
     * already STATUS_FAILED. The default status of the task should be
     * STATUS_OK. Flagging a child will also flag the parent, but not vice
     * versa.
     */
    void flag()
    
    /**
     * Sets the status of this result to STATUS_FAILED. The default status of
     * the task should be STATUS_OK. Failing a child will also fail the parent,
     * but not vice versa.
     */
    void fail()
    
    /**
     * Sets the status of this result to STATUS_DOOMED, which indicates that
     * the failure of the task means the remainder of the test cannot
     * continue successfully, and should be aborted. Dooming a child will also
     * doom the parent, but not vice versa.
     */
    void doom()
}
